<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>B&lt;structure&gt; - an input module B&lt;log2timeline&gt; that parses X</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">


<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#subroutines">SUBROUTINES</a></li>
	<li><a href="#author">AUTHOR</a></li>
	<li><a href="#copyright">COPYRIGHT</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p><strong>structure</strong> - an input module <strong>log2timeline</strong> that parses X</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  my $format = structure;
  require $format_dir . '/' . $format . &quot;.pl&quot; ;</pre>
<pre>
  $format-&gt;verify( $log_file );
  $format-&gt;prepare_file( $log_file, @ARGV )</pre>
<pre>
        $line = $format-&gt;load_line()</pre>
<pre>
  $t_line = $format-&gt;parse_line();</pre>
<pre>
  $format-&gt;close_file();</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>An input module</p>
<p>
</p>
<hr />
<h1><a name="subroutines">SUBROUTINES</a></h1>
<dl>
<dt><strong><a name="get_version" class="item"><code>get_version()</code></a></strong></dt>

<dd>
<p>Return the version number of the input module</p>
</dd>
<dt><strong><a name="get_description" class="item"><code>get_description()</code></a></strong></dt>

<dd>
<p>Returns a string that contains a short description of the functionality if the input module.  When a list of all available input modules is printed using <strong>log2timeline</strong> this string is used.  So this string should be a very short description, mostly to say which type of log file/artifact/directory this input module is designed to parse.</p>
</dd>
<dt><strong><a name="prepare_file" class="item">prepare_file( $file, @ARGV )</a></strong></dt>

<dd>
<p>The purpose of this subfunction is to prepare the log file or artifact for parsing. Usually this involves just opening the file (if plain text) or otherwise building a structure that can be used by other functions.</p>
<p>This function accepts the path to the log file/directory/artifact to parse as well as an array containing the parameters passed to the input module. These parameters are used to adjust settings of the input module, such as to provide a username and a hostname to include in the timeline.</p>
<p>The function returns an integer indicating whether or not it was successful at preparing the input file/directory/artifact for further processing.</p>
</dd>
<dt><strong><a name="load_line" class="item"><code>load_line()</code></a></strong></dt>

<dd>
<p>This function starts by checking if there are any lines in the log file/artifacts that have a date variable inside that needs to be parsed.  It then loads the line (or an index value) in a global variable that can be read by the function parse_line and returns the value 1 to the main script, indicating that a line has been loaded.</p>
<p>When all of the lines in the log file/directory/artifact have been parsed a zero is returned to the main script, indicating that there are no more lines to parse</p>
</dd>
<dt><strong><a name="close_file" class="item"><code>close_file()</code></a></strong></dt>

<dd>
<p>A subroutine that closes the file, after it has been parsed and performs any additional operations needed to close the file/directory/artifact that was parsed (such as to disconnect any database connections)</p>
<p>The subroutine returns an integer indicating whether or not it was successful at closing the file.</p>
</dd>
<dt><strong><a name="parse_line" class="item"><code>parse_line()</code></a></strong></dt>

<dd>
<p>This is the main subroutine of the format file (or often it is).  It depends on the subroutine load_line that loads a line of the log file into a global variable and then parses that line to produce the hash t_line, which is read and sent to the output modules by the main script to produce a timeline or a bodyfile.</p>
<p>The content of the hash t_line is the following:</p>
<pre>
  %t_line {
    md5,    # MD5 sum of the file
    name,    # the main text that appears in the timeline
    title,    # short description used by some output modules
    source,    # the source of the timeline, usually the same name or similar to the name of the package
    user,    # the username that owns the file or produced the artifact
    host,    # the hostname that the file belongs to
    inode,    # the inode number of the file that contains the artifact
    mode,    # the access rights of the file
    uid,    # the UID of the user that owns the file/artifact
    gid,    # the GID of the user that owns the file/artifact
    size,    # the size of the file/artifact
    atime,    # Time in epoch representing the last ACCESS time
    mtime,    # Time in epoch representing the last MODIFICATION time
    ctime,    # Time in epoch representing the CREATION time (or MFT/INODE modification time)
    crtime    # Time in epoch representing the CREATION time
  }</pre>
<p>The subroutine return a reference to the hash (t_line) that will be used by the main script (<strong>log2timeline</strong>) to produce the actual timeline.  The hash is processed by the main script before forwarding it to an output module for the actual printing of a bodyfile.</p>
</dd>
<dt><strong><a name="get_help" class="item"><code>get_help()</code></a></strong></dt>

<dd>
<p>A simple subroutine that returns a string containing the help message for this particular input module. This also contains a longer description of the input module describing each parameter that can be passed to the subroutine.  It sometimes contains a list of all dependencies and possibly some instruction on how to install them on the system to make it easier to implement the input module.</p>
</dd>
<dt><strong><a name="verify" class="item">verify( $log_file )</a></strong></dt>

<dd>
<p>This subroutine takes as an argument the file name to be parsed (file/dir/artifact) and verifies it's structure to determine if it is really of the correct format.</p>
<p>This is needed since there is no need to try to parse the file/directory/artifact if the input module is unable to parse it (if it is not designed to parse it)</p>
<p>It is also important to validate the file since the scanner function will try to parse every file it finds, and uses this verify function to determine whether or not a particular file/dir/artifact is supported or not. It is therefore very important to implement this function and make it verify the file structure without false positives and without taking too long time</p>
<p>This subroutine returns a reference to a hash that contains two values
  success    An integer indicating whether not the input module is able to parse the file/directory/artifact
  msg    A message indicating the reason why the input module was not able to parse the file/directory/artifact</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Kristinn Gudjonsson &lt;kristinn (a t) log2timeline ( d o t ) net&gt; is the original author of the program.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>The tool is released under GPL so anyone can contribute to the tool. Copyright 2009.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>log2timeline</em></p>

</body>

</html>
